/*
 * Course:    CS 590 Web Services
 * Semseter:  Spring 2009
 * Professor: Sedlemeyer
 * Project:   CHEAT (Code Help Educational Assignment Tool)
 * Due Date:  May 1, 2009
 * Team:      Sarcasm
 *            (Baker, Jason; Mitchell, Robin; Shie, Keith)
 */
package cheat.authentication;

import cheat.entities.AccessType;
import cheat.entities.Person;
import cheat.entities.RegisteredUser;
import java.util.List;
import javax.ejb.Remote;

/**
 * Provides the remote interface to the SecurityManagerBean.
 *
 * The security manager contains the functionality related to
 * security/user management.
 *
 * @author Keith Shie
 */
@Remote
public interface SecurityManagerRemote {

  /**
   * <p>Create a new sessions for the user.</p>
   *
   * @param email
   * @param password
   * @return sessionId of the new session.  <p>This value should be passed onto
   * subsequent server methods which require verification/validation.</p>
   *
   * @throws NoSuchRegisteredUserException  <p>If the email isn't known or the password doesn't match.</p>
   */
  int login( String email, String password ) throws NoSuchRegisteredUserException;


  /**
   * <p>Terminate the specified session.</p>
   *
   * <p>Any subsequent servers methods which receive this sessionId
   * will result in an InvalidSessionException.</p>
   *
   * @param sessionId
   * @throws InvalidSessionException If the sessionId isn't recognized.
   */
  void logout( int sessionId ) throws InvalidSessionException;


  /**
   * <p>Create a pending, registered user.</p>
   *
   * <p>If the referenced Person already esists, that Person's
   * values will be updated and linked to the newly created
   * RegisteredUser.</p>
   *
   * <p>If a registered user with the same email already
   * exists, an exception will be thrown.</p>
   *
   * @param user
   * @return false if the user already exists.
   */
  boolean createPendingUser( RegisteredUser user ) throws UserAlreadyRegisteredException;


  /**
   * Provide the access rights for the specified UserSession.
   *
   * @param sessionId Id of the UserSession containing the access rights.
   * @return The requested access rights.
   * @throws cheat.authentication.InvalidSessionException
   */
  AccessType retrieveAccessRights( int sessionId ) throws InvalidSessionException;


  /**
   * <p>Obtain the list users pending approval.</p>
   *
   * <p>Only an ADMIN user is allowed to perform this operation.</p>
   *
   * @param sessionId Id of the session upon which authorization should be
   * based.
   *
   * @return List of users pending registration.
   *
   * @throws InvalidSessionException If the sessionId isn't recognized.
   * @throws InsufficientAccessException  If the associated access level of the session isn't ADMIN.
   */
  List<RegisteredUser> getPendingUsers( int sessionId ) throws InvalidSessionException, InsufficientAccessException;


  /**
   * <p>Activate the specified pending user, allowing access to the system.</p>
   *
   * <p>Only an ADMIN user is allowed to perform this operation.</p>
   *
   * @param sessionId Id of the session upon which authorization should be
   * based.
   *
   * @param email email adress of the user to be activated.
   *
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.authentication.InsufficientAccessException
   * @throws NoSuchRegisteredUserException
   */
  public void activatePendingUser( int sessionId, String email ) throws InvalidSessionException,
                                                                        InsufficientAccessException,
                                                                        NoSuchRegisteredUserException;


  /**
   * <p>Deny the specified pending user access to the system.</p>
   *
   * <p>Only an ADMIN user is allowed to perform this operation.</p>
   *
   * @param sessionId Id of the session upon which authorization should be
   * based.
   *
   * @param email email adress of the user to be activated.
   *
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.authentication.InsufficientAccessException
   * @throws NoSuchRegisteredUserException 
   */
  public void denyPendingUser( int sessionId, String email ) throws InvalidSessionException,
                                                                    InsufficientAccessException,
                                                                    NoSuchRegisteredUserException;


  /**
   * Find a Person with the specified email address.
   *
   * <p>Only an ADMIN user is allowed to perform this operation.</p>
   *
   * @param sessionId Id of the session upon which authorization should be
   * based.
   *
   * @param email email adress of Person to be retrieved.
   *
   * @return The Person specified by the email.
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.authentication.InsufficientAccessException
   */
  public Person getPerson( int sessionId, String email ) throws InvalidSessionException,
                                                                InsufficientAccessException;
}
